<?php

/*
 * Copyright 2008 the original author or authors.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#namespace tehframework\validation;

interface ValidationErrors
{
	const NESTED_PATH_SEPARATOR = '.';
	
	/**
	 * Returns the name of the bound root object.
	 * 
	 * @return string
	 *         The name of the bound root object.
	 */
	function getObjectName();
	
	/**
	 * Allows context to be changed so that standard validators can validate
	 * subtrees. Reject calls prepend the given path to the field names.
	 * 
	 * For example, an address validator could validate the subobject
	 * "address" of a customer object.
	 * 
	 * @param  string $nestedPath
	 *         Nested path within this object, e.g. "address"
	 *         (defaults to "", null is also acceptable).
	 *         Can end with a dot: both "address" and "address." are valid.
	 * @return ValidationErrors
	 */
	function setNestedPath($nestedPath);
	
	/**
	 * Returns the current nested path of this {@link ValidationErrors} object.
	 * 
	 * Returns a nested path with a dot, i.e. "address.", for easy
	 * building of concatenated paths. Default is an empty string.
	 * 
	 * @return string
	 *         The current nested path of this {@link ValidationErrors} object.
	 */
	function getNestedPath();
	
	/**
	 * Pushes the given sub path onto the nested path stack.
	 * 
	 * A {@link popNestedPath()} call will reset the original nested path
	 * before the corresponding pushNestedPath() call.
	 * 
	 * Using the nested path stack allows to set temporary nested paths
	 * for subobjects without having to worry about a temporary path holder.
	 * 
	 * For example: current path "spouse.", pushNestedPath("child") ->
	 * result path "spouse.child."; popNestedPath() -> "spouse." again.
	 * 
	 * @param  string $subPath
	 *         The sub path to push onto the nested path stack.
	 * @return ValidationErrors
	 * @see    popNestedPath()
	 */
	function pushNestedPath($subPath);
	
	/**
	 * Pops the former nested path from the nested path stack.
	 * 
	 * @return ValidationErrors
	 * @throws IllegalStateException
	 *         If there is no former nested path on the stack.
	 * @see    pushNestedPath()
	 */
	function popNestedPath();
	
	/**
	 * Registers a global error for the entire target object,
	 * using the given error description.
	 * 
	 * @param  string $errorCode
	 *         Error code, interpretable as a message key.
	 * @param  array? $errorArgs
	 *         Error arguments, for argument binding via MessageFormat.
	 * @param  string $efaultMessage
	 *         Fallback default message.
	 * @return ValidationErrors
	 */
	function reject($errorCode, array $errorArgs = null, $defaultMessage = null);
	
	/**
	 * Registers a field error for the specified field of the current object
	 * (respecting the current nested path, if any), using the given error
	 * description.
	 * 
	 * The field name may be NULL or empty string to indicate
	 * the current object itself rather than a field of it. This may result
	 * in a corresponding field error within the nested object graph or a
	 * global error if the current object is the top object.
	 * 
	 * @param  string? $field
	 *         The field name.
	 * @param  string $errorCode
	 *         Error code, interpretable as a message key.
	 * @param  array? $errorArgs
	 *         Error arguments, for argument binding via MessageFormat.
	 * @param  string $defaultMessage
	 *         Fallback default message.
	 * @return ValidationErrors
	 * @see    getNestedPath()
	 */
	function rejectValue(
		$field, $errorCode, array $errorArgs = null, $defaultMessage = null);
	
	/**
	 * Adds all errors from the given {@link ValidationErrors} instance
	 * to this instance.
	 * 
	 * This is a convenience method to avoid repeated reject(..)
	 * calls for merging an ValidationErrors instance into another
	 * ValidationErrors instance.
	 * 
	 * Note that the passed-in ValidationErrors instance is supposed
	 * to refer to the same target object, or at least contain compatible errors
	 * that apply to the target object of this ValidationErrors instance.
	 * 
	 * @param  ValidationErrors $errors
	 *         The ValidationErrors instance to merge in.
	 * @return ValidationErrors
	 */
	function addAllErrors(ValidationErrors $errors);
	
	/**
	 * Determines if there were any errors.
	 * 
	 * @return bool
	 *         TRUE if there were any errors; otherwise FALSE.
	 * @see    hasGlobalErrors()
	 * @see    hasAnyFieldErrors()
	 */
	function hasErrors();
	
	/**
	 * Returns the total number of errors.
	 * 
	 * @return int
	 *         The total number of errors.
	 * @see    getGlobalErrorCount()
	 * @see    getFieldErrorCount()
	 */
	function getErrorCount();
	
	/**
	 * Gets all errors, both global and field ones.
	 * 
	 * @return ObjectError[]
	 *         List of {@link ObjectError} instances.
	 */
	function getAllErrors();
	
	/**
	 * Determines whether there are any global errors.
	 * 
	 * @return bool
	 *         TRUE if there are any global errors; otherwise FALSE.
	 * @see    hasFieldErrors()
	 */
	function hasGlobalErrors();
	
	/**
	 * Returns the number of global errors.
	 * 
	 * @return int
	 *         The number of global errors
	 * @see    getFieldErrorCount() 
	 */
	function getGlobalErrorCount();
	
	/**
	 * Gets all global errors.
	 * 
	 * @return ObjectError[]
	 *         List of ObjectError instances.
	 */
	function getGlobalErrors();
	
	/**
	 * Determines whether there are any field errors.
	 * 
	 * @return bool
	 *         TRUE if there are any errors associated with a field.
	 * @see    hasGlobalErrors()
	 * @see    hasFieldErrors()
	 */
	function hasAnyFieldErrors();
	
	/**
	 * Returns the number of errors associated with a field.
	 * 
	 * @return int
	 *         The number of errors associated with a field.
	 * @see    getGlobalErrorCount()
	 * @see    getFieldErrorCount()
	 */
	function getAllFieldErrorCount();
	
	/**
	 * Gets all errors associated with a field.
	 * 
	 * @return FieldError[]
	 *         List of {@link FieldError} instances.
	 */
	function getAllFieldErrors();
	
	/**
	 * Determines whether there are any errors associated with the given field.
	 * 
	 * @param  string $field
	 *         The field name.
	 * @return bool
	 *         TRUE if there were any errors associated with the given field;
	 *         otherwise FALSE.
	 */
	function hasFieldErrors($field);
	
	/**
	 * Returns the number of errors associated with the given field.
	 * 
	 * @param  string $field
	 *         The field name.
	 * @return int
	 *         The number of errors associated with the given field.
	 */
	function getFieldErrorCount($field);
	
	/**
	 * Get all errors associated with the given field.
	 * 
	 * Implementations should support not only full field names like
	 * "name" but also pattern matches like "na*" or "address.*".
	 * 
	 * @param  string $field
	 *         The field name.
	 * @return FieldError[]
	 *         List of {@link FieldError} instances.
	 */
	function getFieldErrors($field);
	
	/**
	 * Return the current value of the given field, either the current
	 * bean property value or a rejected update from the last binding.
	 * 
	 * Allows for convenient access to user-specified field values,
	 * even if there were type mismatches.
	 * 
	 * @param  string $field
	 *         The field name.
	 * @return mixed
	 *         The current value of the given field.
	 */
	function getFieldValue($field);
	
	/**
	 * Return the type of a given field.
	 * 
	 * Implementations should be able to determine the type even
	 * when the field value is NULL, for example from some
	 * associated descriptor.
	 * 
	 * @param  string $field
	 *         The field name.
	 * @return string
	 *         The type of the field, or NULL if not determinable.
	 */
	function getFieldType($field);
}